Helpbook Implementation

Requirements

App Info.plist:

   <key>CFBundleHelpBookFolder</key>       <string>WinManTJS Help</string>  Note: the space causes name truncation when help cache is generated.
   <key>CFBundleHelpBookName</key>         <string>WinManTJS Help</string>
   <key>CFBundleShortVersionString</key>   <string>7.3</string>

Help bundle Info.plist:

  <key>CFBundleDevelopmentRegion</key>
  <string>en</string>
  <key>CFBundleIdentifier</key>
  <string>uk.wanderinghippo.WinManTJS.help</string>
  <key>CFBundleInfoDictionaryVersion</key>
  <string>6.0</string>
  <key>CFBundleName</key>
  <string>WinManTJS Help</string>
  <key>CFBundlePackageType</key>
  <string>BNDL</string>
  <key>CFBundleShortVersionString</key>
  <string>1.0</string>
  <key>CFBundleVersion</key>
  <string>1</string>
  <key>CFBundleSignature</key>
  <string>hbwr</string>
  <key>HPDBookAccessPath</key>
  <string>index.html</string>
  <key>HPDBookIconPath</key>
  <string>helpBookIcon.png</string>
  <key>HPDBookIndexPath</key>
  <string>WinManTJS Help.cshelpindex</string>
  <key>HPDBookTitle</key>
  <string>WinManTJS Help</string>
  <key>HPDBookType</key>
  <string>3</string>

Help bundle: Entry page (index.html) contains -

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE html>
  <html xmlns="http://www.w3.org/1999/xhtml">

Note: Old updated Apple docs suggest the index/landing page be XHTML (for best performance). HTML 4.0 was required for earlier OSX releases.

  <meta charset="utf-8" />
  <title>WinManTJS Help</title>
  <meta name="AppleTitle" content="WinManTJS Help" />
  <meta name="robots" content="anchors" />    // content may include "index" depending on page content

Helpbook Indexing

Only need a .cshelpindex file on later macOS releases to feed Spotlight - in this case WinManTJS Help.cshelpindex (this becomes en.cshelpindex in the generated cache)

Run from en.lproj folder -

hiutil -I corespotlight -Ca -f WinManTJS\ Help.cshelpindex . -vv
 - created WinManTJS.cshelpindex in en.lproj - . specifies the dir to be indexed (needed)

hiutil -I lsm  -Ca -f WinManTJS\ Help.helpindex . -vv     //  Note: this is the legacy indexing for pre-Silicon Macs.
 - created WinManTJS.helpindex in en.lproj - . specifies the dir to be indexed


  check content of index file -

hiutil -I corespotlight -Tvf WinManTJS\ Help.cshelpindex

Cache entry in Generated will happen when installed app initially uses the Help search box in the menu (no need to wait for OS to register helpbook). Cache path including a version will use the CFBundleShortVersionString key from the app plist.

Generated Cache entry -

Users/USER/Library/Caches/com.apple.helpd/Generated/uk.wanderinghippo.WinManTJS.help*7.3/en.cshelpindex  // *7.3 added if ShortVersion key present in app plist

There appears to be another cache used by the OS but not sure when it is used - possibly when apps are run from outside the Applications folder.

Group Cache -

Users/USER/Library/Group Containers/group.com.apple.helpviewer.content/Library/Caches

macOS appears to combine details from both the app bundle plist and the help bundle plist for the Cache name.

Cache entry - uk.wanderinghippo.WinManTJS.uk.wanderinghippo.WinManTJS.help*7.3.help

          App bundle plist                     Help bundle plist                       App bundle plist
  <key>CFBundleIdentifier</key> + . + <key>CFBundleIdentifier</key> + * + <key>CFBundleShortVersionString</key> + . + help

  <string>uk.wanderinghippo.WinManTJS</string> + . + <string>uk.wanderinghippo.WinManTJS.help</string> + * + <string>7.3</string> + . + help

Helpbook Integration

As of v0.50.1 of TJS there is no implementation for integrating helpbooks.

Helpbooks seem to integrate easier using a bundle folder rather than a .help bundle (eg: WinManTJS Help rather than WinManTJS Help.help) but YMMV.

Manual Integration:

Place helpbook bundle into root of Resources folder of app bundle.
Edit app bundle Info.plist with details as described above.

A rebuild of the source binaries can achieve an integration ( see TJS Build ).